feat: add TOML v1.0 serialization support#2828
feat: add TOML v1.0 serialization support#2828Thyago-Oliveira-Perez wants to merge 1 commit intomicrosoft:mainfrom
Conversation
Adds OpenApiTomlWriter (mirrors OpenApiJsonWriter / OpenApiYamlWriter),
a new OpenApiConstants.Toml constant, and SerializeAsTomlAsync extension
methods so callers can export an OpenAPI document as TOML.
Public API declared in PublicAPI.Unshipped.txt; RS0026 suppressed for
consistency with existing SerializeAsJson/YamlAsync overloads.
|
@microsoft-github-policy-service agree |
baywet
left a comment
baywet
left a comment
There was a problem hiding this comment.
Hi @Thyago-Oliveira-Perez
Thank you for using the SDK and for reaching out.
Thanks for the contribution!
I'm a bit mixed on this proposal and wished you had started by creating an issue first to have a discussion.
OpenAPI descriptions are by design deeply nested, and TOML does not seem to be designed for that. Additionally, the ecosystem support for TOML, and demand for it is low to inexistant. (no prior issue on the matter)
As for this PR: I'm really questioning the usefulness of having the ability to serialize to, but not deserialize from TOML. I understand this might be useful to convert and push to other systems that only accept TOML, but I'd be surprised to see any system that only accepts TOML in 2026. Implementing the deserialization would need to be done in a companion library like yaml is done today. And would allow us to validate roundtrips actually work.
Before we make any further code changes, can you please expand on why you think TOML is necessary? Why it needs to be in the "official library" (and not in a community owned peer)? And what you're trying to achieve (beyond supporting TOML)?
Thanks!
|
Thanks for the feedback @baywet. That’s fair, and I agree I should have opened an issue first. The motivation here isn’t really adding TOML support for the sake of it, but solving a "problem" I'm having. I’ve been using OpenAPI as input for AI-assisted workflows (mainly generating frontend code), and JSON/YAML aren’t great in that context. TOML ended up being better in that context as it is more predictable format and consume less tokens for prompts. So the idea is more about having a readable/export-friendly projection. On serialization without deserialization, I agree it’s a limitation. My assumption was that this would behave more like an export format, but I see your point that proper support would likely require a companion package (like YAML). Regarding being in the official library: my thinking was mostly around keeping it close to the existing serialization logic to avoid fragmentation, but I’m totally open to moving this to a separate/experimental package if that fits better. Happy to open an issue and continue the discussion there if you prefer. |
|
Hi @Thyago-Oliveira-Perez
I'm not sure how that claim stands? Depending on the scenarios, and from cursory search, TOML appears to use the same number of characters (blank spaces excluded) than YAML or JSON. Except for deeply nested structures where it's worse. Do you have examples that would illustrate this?
From an integration tests perspective, having the ability to roundtrip often leads to the discovery of defects, improving the quality.
I think it'd make more sense to have this a its own library for now. And if we start seeing a lot of demand for it, we'll evaluate moving things into this repository, does that make sense? Let me know if you have any additional comments or questions. |
2 participants
Pull Request
Description
Type of Change
Related Issue(s)
Changes Made
Testing
Checklist
Versions applicability
See the contributing guidelines for more information about how patches are applied across multiple versions.
Additional Notes